Developer CD Series 1996 June: Reference Library/Dev.CD Jun 96 RL/Dev.CD Jun 96 RL.toast/What's New?/Development Kits/Apple Game Sprockets DR1/Headers/InputSprocket.h

Text File | 1996-04-24 | 14.7 KB | 631 lines | [TEXT/MPS ]

//
// InputSprocket.h  0.2
// 3/14/96
//

#ifndef __InputSprocket__
#define __InputSprocket__

#ifdef __cplusplus
extern "C" {
#endif

// ********************* data types *********************
#include <DriverServices.h>

#ifndef opaque
#define opaque void *
#endif

typedef struct opaqueDeviceData *DeviceReference;
typedef struct opaqueElementData *ElementReference;
typedef struct opaqueElementListData *ElementListReference;
typedef OSType ElementLabel;
typedef OSType ElementKind;

/*
 * DeviceDefinition
 *
 * This structure provides all the available
 * information for an input device within the system
 *
 */

typedef struct
{
    OSType deviceType;            // every distinguishable device should have an OSType
    UInt32 permanentId;            // a cross reboot id unique within that deviceType, 0 if not possible
} DeviceDefinition;

/*
 * ElementEvent, ElementEventPtr
 *
 * This is the structure that event data is passed in.
 *
 */

typedef struct
{
    AbsoluteTime when;                  // this is absolute time on PCI or later, otherwise it is
                                        // 0 for the hi 32 bits and TickCount for the low 32 bits
    ElementReference element;            // a reference to the element that generated this event
    UInt32 refCon;                        // for application usage, 0 on the global list
    SInt32 data;                        // the data for this event
} ElementEvent, *ElementEventPtr;

/*
 * ElementInfo, ElementInfoPtr
 *
 * This is the generic definition of an element.
 * Every element must contain this information.
 *
 */
typedef struct ElementInfo
{
    ElementLabel theLabel;
    ElementKind theKind;
    Str63 theString;
} ElementInfo, *ElementInfoPtr;

/*
 * These are the current built in ElementKind's
 *
 * These are all OSTypes.
 *
 */

enum
{
    kElementKindTrigger = 'trig',
    kElementKindButton = 'butn',
    kElementKindDPad = 'dpad',
    kElementKindAxis = 'axis'
};


/*
 *
 * These are the current built in ElementLabel's
 *
 * These are all OSTypes.
 *
 */

enum
{
    // axis
    kElementLabelXAxis = 'xaxi',
    kElementLabelYAxis = 'yaxi',
    kElementLabelZAxis = 'zaxi',

    kElementLabelRx = 'rxax',
    kElementLabelRy = 'ryax',
    kElementLabelRz = 'rzax',

    kElementLabelGas = 'gasp',
    kElementLabelBrake = 'brak',
    kElementLabelClutch = 'cltc',

    kElementLabelThrottle = 'thrt',
    kElementLabelTrim = 'trim',

    // direction pad
    kElementLabelPOVHat = 'povh',
    kElementLabelPadMove = 'move',

    // buttons
    kElementLabelFire = 'fire',
    kElementLabelStart = 'strt',
    kElementLabelSelect = 'optn'
};

/*
 *
 * direction pad data & configuration information
 *
 */

typedef enum
{
    kPadIdle = 0,
    kPadLeft,
    kPadUpLeft,
    kPadUp,
    kPadUpRight,
    kPadRight,
    kPadDownRight,
    kPadDown,
    kPadDownLeft
} DPadData;

typedef struct
{
    UInt32 id;                // ordering 1..n, 0 = no relavent ordering of direction pads
    Boolean fourWayPad;        // true if this pad can only produce idle + four directions
} DPadConfigurationInfo;

/*
 *
 * button data & configuration information
 *
 */

typedef enum
{
    kButtonUp = 0,
    kButtonDown = 1
} ButtonData;

typedef struct
{
    UInt32 id;                // ordering 1..n, 0 = no relavent ordering of buttons / triggers
} ButtonConfigurationInfo;

/*
 *
 * trigger data & configuration information
 *
 */

typedef enum
{
    kTriggerActivated = 1
} TriggerData;

typedef struct
{
    UInt32 id;                // ordering 1..n, 0 = no relavent ordering of buttons / triggers
} TriggerConfigurationInfo;

/*
 *
 * axis data & configuration information
 *
 */

typedef enum
{
    kAxisCenter = 0,
    kAxisMaximum = 0x7FFFFFFFL,
    kAxisMinimum = 0x80000000L
} AxisData;

typedef struct
{
    Boolean    SymetricAxis;    // axis is symetric and can produce both positive and negative data
} AxisConfigurationInfo;

// ********************* user level functions *********************

/*
 * GetDeviceDefinition
 *
 * pass in the device reference, sizeof(DeviceDefinition) and this will
 * return the device definition struct for that device into the buffer pointed to
 * by outStruct
 *
 * Return Codes
 * paramErr
 *
 */

OSStatus GetDeviceDefinition(const DeviceReference inDevice, UInt32 buflen, DeviceDefinition *outStruct);


/*
 *
 * GetDeviceElementList
 *
 * pass in the device reference and this will return the element list for that device
 * you are prohibited from modifiying this element list
 *
 * Return Codes
 * paramErr
 *
 */

OSStatus GetDeviceElementList(const DeviceReference inDevice, ElementListReference *outElementList);

/*
 *
 * takes an ElementReference and returns the group that it is in or
 * nil if there is no group
 *
 * Return Codes
 * paramErr if inElement is 0
 *
 */

OSStatus GetElementGroup(const ElementReference inElement, UInt32 *outGroup);

/*
 *
 * takes an ElementReference and returns the device that the element belongs
 * to.
 *
 * Return Codes
 * paramErr if inElement is 0or outDevice is nil
 *
 */

OSStatus GetElementDevice(const ElementReference inElement, DeviceReference *outDevice);

/*
 *
 * takes an ElementReference and gives the ElementInfo for that Element.  This is the
 * the set of standard information.  You get ElementKind specific information
 * through GetElementConfigurationInfo.
 *
 * Return Codes
 * paramErr if inElement is 0 or outInfo is nil
 *
 */

OSStatus GetElementInfo(const ElementReference inElement, ElementInfoPtr outInfo);

/*
 *
 *
 *
 * takes an ElementReference and gives the ElementKind specific configuration information
 *
 * if buflen is not long enough to hold the information GetElementConfigurationInfo will
 * copy buflen bytes of the data into the block of memory pointed to by configInfo and
 * will return something error.
 *
 * Return Codes
 * paramErr if inElement or configInfo is nil
 * something error if buflen is not long enough to hold the information
 *
 */

OSStatus GetElementConfigurationInfo(const ElementReference inElement, UInt32 buflen, void *configInfo);

/*
 *
 * GetElementSimpleState
 *
 * Takes an ElementReference and returns the current state of that element.  This is a
 * specialized version of GetElementComplexState that is only appropriate for elements
 * whose data fits in a signed 32 bit integer.
 *
 *
 *
 * Return Codes
 * paramErr if inElement is 0 or state is nil
 * err1 if the elements data does not fit in a signed 32 bit integer
 *
 */

OSStatus GetElementSimpleState(const ElementReference inElement, SInt32 *state);

/*
 *
 * GetElementComplexState
 *
 * Takes an ElementReference and returns the current state of that element.
 * Will copy up to buflen bytes of the current state of the device into
 * state.
 *
 *
 * Return Codes
 * paramErr if inElement is 0 or state is nil
 * err2 if buflen is not large enough to hold all the data
 *
 */

OSStatus GetElementComplexState(const ElementReference inElement, UInt32 buflen, void *state);


/*
 * ElementGetNextEvent
 *
 * changed 3/14/96
 *
 * It takes in an element  reference and the buffer size of the ElementEventPtr
 * it will set wasEvent to true if there was an event and false otherwise.  If there
 * was not enough space to fill in the whole event structure that event will be
 * dequed, as much of the event as will fit in the buffer will by copied and
 * ElementGetNextEvent will return an error.
 *
 * Return Codes
 * paramErr
 * somethingErr - buffer to small
 */

OSStatus ElementGetNextEvent(ElementReference inElement, UInt32 bufSize, ElementEventPtr event, Boolean *wasEvent);

/*
 *
 * ElementFlush
 *
 * It takes an ElementReference and flushes all the events on that element.  All it guaruntees is
 * that any events that made it to this layer before the time of the flush call will be flushed and
 * it will not flush any events that make it to this layer after the time when the call has returned.
 * What happens to events that occur during the flush is undefined.
 *
 *
 * Return Codes
 * paramErr
 *
 */

OSStatus ElementFlush(ElementReference inElement);



/*
 * NewElementList
 *
 * Creates a new element list and returns it in outElementList
 *
 *
 * Return Codes
 * out of memory - If it failed to allocate the list because it was out of memory
                   it will also set outElementList to 0
 * paramErr if outElementList was nil
 *
 *
 * Special Concerns
 *
 * interrupt unsafe
 *
 */

OSStatus NewElementList(ElementListReference *outElementList);

/*
 * DisposeElementList
 *
 * Deletes an already existing memory list.
 *
 *
 * Return Codes
 * paramErr if inElementList was 0
 *
 *
 * Special Concerns
 *
 * interrupt unsafe
 *
 */

OSStatus DisposeElementList(ElementListReference inElementList);

/*
 * GetGlobalElementList
 *
 * returns the global element list
 *
 * Return Codes
 * paramErr if outElementList is nil
 *
 */

OSStatus GetGlobalElementList(ElementListReference *outElementList);

/*
 * ElementListAddElement
 *
 * adds an element to the element list
 *
 * Return Codes
 * paramErr if inElementList is 0 or newElement is 0
 * memory error if the system is unable to allocate enough memory
 *
 * Special Concerns
 * interrupt Unsafe
 *
 */
OSStatus ElementListAddElement(ElementListReference inElementList, UInt32 refCon, ElementReference newElement);

/*
 * ElementListRemoveElement
 *
 * removes the specified element from the element list
 *
 * Return Codes
 * paramErr if inElementList is 0 or oldElement is 0
 * memory error if the system is unable to allocate enough memory
 *
 * Special Concerns
 * interrupt Unsafe
 *
 */

OSStatus ElementListRemoveElement(ElementListReference inElementList, ElementReference oldElement);

/*
 * ElementListExtract
 *
 * ElementListExtract will extract as many of the elements from an element list as possible.  You pass
 * in an element list, a pointer to an array of element references and the number of elements in that array.
 * It will return how many items are in the element list in the outCount parameter and copy the minimum of
 * that number and the size of the array into the buffer.
 *
 * ByKind and ByLabel are the same except that they will only count and copy element references to elements
 * that have the specified kind and label.
 *
 * Return Codes
 * paramErr
 *
 */

OSStatus ElementListExtract(ElementListReference inElementList, UInt32 inBufferCount, UInt32 *outCount, ElementReference *buffer);
OSStatus ElementListExtractByKind(ElementListReference inElementList, ElementKind theKind, UInt32 inBufferCount, UInt32 *outCount, ElementReference *buffer);
OSStatus ElementListExtractByLabel(ElementListReference inElementList, ElementLabel theLabel, UInt32 inBufferCount, UInt32 *outCount, ElementReference *buffer);

/*
 * ElementListGetNextEvent
 *
 * changed 3/14/96
 *
 * It takes in an element list reference and the buffer size of the ElementEventPtr
 * it will set wasEvent to true if there was an event and false otherwise.  If there
 * was not enough space to fill in the whole event structure that event will be
 * dequed, as much of the event as will fit in the buffer will by copied and
 * ElementListGetNextEvent will return an error.
 *
 * Return Codes
 * paramErr
 * somethingErr - buffer to small
 */

OSStatus ElementListGetNextEvent(ElementListReference inElementList, UInt32 bufSize, ElementEventPtr event, Boolean *wasEvent);

/*
 *
 * ElementListFlush
 *
 * It takes an ElementListReference and flushes all the events on that list.  All it guaruntees is
 * that any events that made it to this layer before the time of the flush call will be flushed and
 * it will not flush any events that make it to this layer after the time when the call has returned.
 * What happens to events that occur during the flush is undefined.
 *
 *
 * Return Codes
 * paramErr
 *
 */

OSStatus ElementListFlush(ElementListReference inElementList);


// ********************* driver level functions *********************


/*
 *
 * NewDevice
 *
 * This creates a new device from the device definition structure and returns
 * the result into the device reference.
 *
 * Returns Codes
 * paramErr
 * out of memory
 *
 * Specical Considerations
 * may not be done at interrupt time
 */

OSStatus NewDevice(const DeviceDefinition *inStruct, DeviceReference *outReference);

/*
 * DisposeDevice
 *
 * This disposes an existing device.
 *
 * Returns Codes
 * paramErr
 *
 * Special Considerations
 * May not be done at interrupt time
 *
 */

OSStatus DisposeDevice(DeviceReference *inReference);

/*
 *
 * ElementDefinitionStruct
 *
 * This is the structure that defines everything static about this
 * element.  For each element on your device you will need to
 * fill in one of these structures when your driver loads.
 *
 */

typedef struct
{
    DeviceReference device;  // device this element belongs to
    UInt32 group;             // group this element belongs to or 0

    Str63 theString;         // a string that is a human readable identifier for this element, internationalization ?

    ElementKind kind;
    ElementLabel label;

    void *configInfo;         // a pointer to the buffer containing the configuration information for this element
    UInt32 configInfoLength; // length of that configuration info

    UInt32 dataSize;         // the size of the data, so we can generate an appropriate buffer
} ElementDefinitionStruct;

/*
 *
 * NewElement
 *
 * NewElement takes an element definition struct and gives you back a element reference.
 * When you produce data you use that element reference to give the data to the system.
 *
 * Return Codes
 * paramErr
 * memory error
 *
 * Special Considerations
 * The NewElement function may move or purge memory.  Your application should not call this function
 * at interrupt time.
 *
 */

OSStatus NewElement(const ElementDefinitionStruct *inStruct, ElementReference *outElement);

/*
 *
 * DisposeElement
 *
 * DisposeElement takes an element reference and deletes it.
 * You should call this function when your driver unloads.
 *
 * Return Codes
 * paramErr
 * memory error
 *
 * Special Considerations
 * The DisposeElement function may move or purge memory.  Your application should not call this function
 * at interrupt time.
 *
 */

OSStatus DisposeElement(ElementReference inElement);

/*
 *
 * ElementPushSimpleData
 *
 * ElementPushSimpleData is the appropriate way to give the system data if your data fits exactly into
 * a 32 bit signed number.  You pass the element reference that goes with the data, the data and the
 * AbsoluteTime that data was produced.  If UpTime is not available you should fill time.lo with the
 * TickCount time and time.hi with 0.
 *
 * Return Codes
 * paramErr
 *
 */

OSStatus ElementPushSimpleData(ElementReference inElement, SInt32 data, const AbsoluteTime *time);

/*
 *
 * ElementPushComplexData
 *
 * ElementPushComplexData is exactly like ElementPushSimpleData except that it is appropriate for times
 * when your data does not fit into a signed 32 bit integer.
 *
 * Instead it takes the length of your data (which must match the datasize field of your ElementDefinitionStruct)
 * and a ptr to the devices state.
 *
 * Return Codes
 * paramErr
 *
 */

OSStatus ElementPushComplexData(ElementReference inElement, UInt32 buflen, void *state, const AbsoluteTime *time);

#ifdef __cplusplus
}
#endif

#endif // __InputSprocket__